Skip to content

fix(control-plane): resolve checkpoint artifacts after runtime relocation - #9163

Merged
huangruiteng merged 1 commit into
mainfrom
cursor/checkpoint-relocated-run-path-6200
Nov 21, 2026
Merged

huangruiteng merged 1 commit into
mainfrom
cursor/checkpoint-relocated-run-path-6200

Conversation

@Duang777

Copy link
Copy Markdown
Collaborator

Goal And Delivered Outcome

Author Declaration

Implemented against

Criterion (spec clause) Disposition Symbol / path Test or command
Remap absolute <any>/goals/<goalId>/runs/<file> to the current runs file when it is a regular file inside that directory implemented runPath / relocatedCheckpointArtifact in loopx/control_plane/goals/checkpoint_commit.ts tests/control_plane_ts/checkpoint_commit.test.ts relocated-runtime case
Reject other goals, outside paths, traversal, symlinks, and non-files implemented same helper same file, reject cases
Do not change quota spend reading, monitor-poll, or void receipts implemented no edits in those owners tests/control_plane_ts/quota_spend_commit.test.ts still passes
  • Self-check before submission: confirmed settlement_readback.ts returns writeback_run unmapped and state_refresh.py passes that row into inspect_checkpoint_replay. Ran the new test on unmodified runPath and saw it fail, then applied the helper change and re-ran the checks below. Did not run a full commitCheckpoint settlement-admission integration; replay and the supplement write both call this same runPath.

Scope And Continuation

  • Completed scope and remaining work: complete for checkpoint artifact resolution in runPath. In-flight monitor-poll and void transaction receipts are unchanged.
  • Slice boundary / successor: no successor. A later receipt owner should use this same containment rule only if a reachable hole is proven there.

Validation

  • Tested revision: a3d87641dedc8413bb36bf13dddf43f8bc3d689f
  • Run state: finished
  • Input classes: synthetic
Check kind Result Public-safe evidence / limitation
regression_parity failed then passed Before the helper change, node --no-warnings --experimental-strip-types --test tests/control_plane_ts/checkpoint_commit.test.ts on main plus the new test: 4 tests, 1 failed, 3 passed. Failure: inspectCheckpointReplay reads checkpoint artifacts copied into a relocated runtime with checkpoint artifact path is invalid; read back the original Turn before retrying (checkpoint_commit_unknown). The in-directory read and the outside-path / symlink / non-file rejects passed.
unit passed Same command after the fix: 4 passed, 0 failed. The success case asserts the returned paths and bytes are the relocated artifact_bytes: relocated-runtime / relocated markdown, not the stale original.
unit passed node --no-warnings --experimental-strip-types --test on checkpoint_commit.test.ts, quota_spend_commit.test.ts, vision_checkpoint.test.ts, checkpoint_read_context.test.ts, checkpoint_artifacts.test.ts, checkpoint_provider_head.test.ts, checkpoint_retention.test.ts, open_todo_semantic_checkpoint.test.ts, refresh_recovery.test.ts, vision_wait_coverage.test.ts: 121 passed, 0 failed.
static passed npx tsc --project tsconfig.control-plane.json --noEmit (npm run typecheck:control-plane): exit 0.
static passed uv run --extra test python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation: all checks passed. git diff --check: clean. python scripts/check_rfc_bilingual.py --base origin/main --head HEAD: passed. No paired RFC changed.
static passed loopx canary premerge --from-git-diff --git-diff-base origin/main on this head: ok=true, status=passed, changed_files=3, surfaces=control_plane, direct checks 4/4, catalog canaries 6/6, risk-profile smokes 8/8, failures 0. self_merge_allowed=false.
  • Coverage and gaps: the new test covers the refresh replay read (inspectCheckpointReplay → committedArtifacts → runPath), including a missing copy that must not fall back to the old file. commitCheckpoint replay and supplement write use the same helper, but this PR does not drive the settlement lock/admission harness. Monitor-poll and void receipt paths were not changed and were not re-proved beyond the existing spend suite.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • First viewport and preview: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A
  • Craft review: N/A

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Refactoring (no functional changes)
  • Documentation update
  • Test update

LoopX Area

  • Control plane (goals, todos, quota, scheduler, registry, runtime)
  • Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
  • Capability or extension (providers, adapters, skills)
  • Public docs or presentation surface (README, protocols, dashboard)
  • Build, packaging, installer, or CI
  • Host or runtime integration

Technical Direction

  • Direction / acceptance reference, when applicable: control-plane settlement recovery. Not a roadmap id.

Shared-authority RFC fixture impact

  • N/A

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Existing English/Chinese RFC pairs (including ledger entries) both have a diff, and the local premerge check python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD passes, or no paired RFC changed.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).
Open in Web Open in Cursor 

…tion

runs/index.jsonl can keep absolute json_path and markdown_path values after
a runtime_root copy. Quota spend reads already remap those paths (#9161);
checkpoint replay still required the stored directory to be the current
runs directory, so refresh-state replay and repair rejected the copied
artifact.

runPath now resolves an absolute <any>/goals/<goalId>/runs/<file> path to
that file name inside the current goal runs directory when the entry is a
regular file, and still rejects other goals, outside paths, traversal, and
non-files.

Signed-off-by: Duang777 <[email protected]>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Antigravity · Google Deepmind · self_reported

动机 / Motivation

复制或迁移过 runtime_root 后触发 refresh-state 重放、回执修复或幂等结算检查点的控制面调用方与运行维护者。 此前,runs/index.jsonl 中历史记录保存了旧运行根目录下的绝对 json_path 与 markdown_path;在 #9161 已修复 quota spend 路径重映射后,checkpoint_commit.ts 的 runPath 仍强制要求路径目录严格等于当前 runsDir,导致 inspectCheckpointReplay 与 commitCheckpoint 重放阶段抛出 checkpoint artifact path is invalid 并阻断恢复。改动后,当路径满足 <任意目录>/goals/<goalId>/runs/<文件名> 且当前目标的 runs 目录下存在同名常规文件(经 realpathSync 校验未越界、非符号链接)时,改用新目录下的当前产物文件。

跨 runtime_root 拷贝后的合法 checkpoint 重放能够读取并校验新运行根目录下的同名 .json/.md 产物(而非误读旧目录残余文件);其它 Goal、越界路径、目录穿越 ..、符号链接逃逸或内部符号链接以及缺失副本仍以原有错误码与措辞拒绝。 本 PR 不改动 quota spend 读路径(#9161)、monitor_poll_commit.ts、void 交易回执、也未运行完整的 commitCheckpoint 锁交接/结算准入集成 harness(仅复用共享的 runPath 路径校验边界)。

由于此前同批已有 #9161 修复了 spend 产物读取(readQuotaSpendEventFromRun),若放任 checkpoint_commit.ts 保持硬编码目录相等检查,任何已拷贝隔离的 runtime_root 在执行 refresh-state 回放或修复时都会卡死在合法历史检查点读取上;本次小幅修补直接补齐了该缺口且具备完整可回滚边界。

改动思路 / Approach

将跨运行根目录的重定位文件名解析内聚在既有的同步控制面边界 checkpoint_commit.ts(runPath / relocatedCheckpointArtifact)中,利用同步 lstatSync/realpathSync 保持 withCheckpointHead 无异步挂起与防符号链接逃逸不变量。 当前 PR 仅修复 checkpoint_commit.ts 中 committedArtifacts 与写入共用的 runPath 校验及其单元测试并纳管 tsconfig.control-plane.json,不新增状态存储、配置开关或跨模块重构。

场景 改动前(1488ec10dd) 改动后(a3d87641de)
同目录常规文件 / 新建写入路径 dirname(path) === resolve(runsDir) 通过 保持原有直通分支与 ENOENT 允许新建语义不变
拷贝后 <old>/goals/<goalId>/runs/<file> 直接抛出 checkpoint artifact path is invalid 经 relocatedCheckpointArtifact 映射至当前 realpathSync(runsDir)/<file> 并校验非符号链接常规文件
跨 Goal / 外部路径 / .. 穿越 拒绝 仍返回 null 并以 checkpoint artifact path is invalid 拒绝
当前目录下符号链接(外部或内部别名)或目录 拒绝 lstatSync 非常规文件且 relativePath !== fileName,一律拒绝(不回退读取旧路径)

在设计复用比较上,accounting_artifact_transaction.ts 的 readQuotaSpendEventFromRun(#9161)使用异步 fs/promises 且仅处理 .json、允许缺省返回 null;而 checkpoint_commit.ts 内部在 withCheckpointHead 临界区内要求严格同步执行(禁止 await)且同时校验 .json 与 .md 并拒绝内部符号链接。因此在既有 checkpoint_commit.ts 内保留同步的 relocatedCheckpointArtifact 助手,比跨文件引入异步接口更契合同步锁约束。

具体改动 / Changes

本次改动共涉及 3 个文件(+223 / -16):loopx/control_plane/goals/checkpoint_commit.ts(+52 / -16)、新增 tests/control_plane_ts/checkpoint_commit.test.ts(+170)以及 tsconfig.control-plane.json(+1)。

本切片无独立书面 RFC 规范(no_spec);其交付依据为本次 PR 的修复目标与 #9161 在 readQuotaSpendEventFromRun 建立的相邻路径重定位行为,并在 inspectCheckpointReplay 的实际入口与反例用例中完成对照验证。

关键代码讲解

  1. relocatedCheckpointArtifact(loopx/control_plane/goals/checkpoint_commit.ts):校验原始路径必须为绝对路径;经 resolve 规范化后逐级检查父目录结构严格为 .../goals/<goalId>/runs/<fileName>,且 extname(fileName) === extension(排除 .json 类无主文件名与错误扩展名)。随后对当前 runsDir 取 realpathSync,仅当 join(runsDirReal, fileName) 经 lstatSync 确认为常规文件、再经 realpathSync 计算相对路径严格等于 fileName 时返回规范化新路径;目录不存在或校验不符均返回 null。
  2. runPath 与 committedArtifacts(loopx/control_plane/goals/checkpoint_commit.ts):将 goalId 从 inspectCheckpointReplay 及 commitCheckpoint 的回放/补充写入路径传入 committedArtifacts 与 runPath。当路径位于当前 resolve(runsDir) 下时沿用既有逻辑(含新建文件尚未落盘时的 ENOENT 放行);仅当目录不匹配时转入 relocatedCheckpointArtifact,失败则抛出原有的 checkpoint artifact path is invalid(错误码 checkpoint_commit_unknown)。
  3. 单元测试套件(tests/control_plane_ts/checkpoint_commit.test.ts):构造独立 originalRoot 与 relocatedRoot,显式验证读取结果返回新目录路径与 "relocated-runtime" 字节内容(未误读旧目录 "stale-original"),并覆盖缺失副本、跨 Goal、目录外路径、.. 穿越、外部符号链接、同目录符号链接别名及目录冒充等全部负向反例。

对主干的风险 / Risks

验证执行矩阵

  • changed_invariant_positive(PASS):npm run typecheck:control-plane(exit 0);Node TypeScript 测试覆盖 checkpoint_commit.test.ts、quota_spend_commit.test.ts、vision_checkpoint.test.ts、checkpoint_read_context.test.ts、checkpoint_artifacts.test.ts、checkpoint_provider_head.test.ts、checkpoint_retention.test.ts、open_todo_semantic_checkpoint.test.ts、refresh_recovery.test.ts、vision_wait_coverage.test.ts 共 121/121 通过(0 失败);Python inspect_checkpoint_replay 经真实 TS effect runtime 跨目录迁移实测通过。
  • material_negative_or_failure(PASS):实测基线 1488ec10dd 的 inspectCheckpointReplay 在迁移目录样本上复现失败(抛出 checkpoint artifact path is invalid; read back the original Turn before retrying),当前头 a3d87641de 通过;额外独立反例验证了 .json 隐式点文件名、相对路径均被拒绝,且符号链接形式的 runtime_root 别名可正确解析至 realpath 并返回对应副本;缺失目标副本时 Python inspect_checkpoint_replay 以 checkpoint_commit_unknown 拒绝。
  • repository_required_checks(PASS):ruff check(tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation)通过;scripts/check_rfc_bilingual.py 通过;git diff --check 干净;loopx check --scan-path 扫描 3 个变更文件 0 错误 0 警告;loopx canary premerge(14 项检查:4 项直接检查、6 项目录金丝雀含 semantic-vocabulary-drift-smoke.py、8 项风险特征 smoke)全部通过(0 失败)。Python checkpoint/refresh 相关套件共 180 passed, 14 skipped(test_refresh_checkpoint_recovery + test_refresh_checkpoint_isolation + test_codex_checkpoint_context_refresh + test_checkpoint_provider_fence + test_checkpoint_read_context 85 passed;test_research_checkpoint_capture + test_research_checkpoint_cli + test_vision_wait_coverage 82 passed, 12 skipped 因未设置 LOOPX_NATIVE_CHECKPOINT_BIN;test_refresh_settlement_recovery 13 passed, 2 skipped 因未安装 pwsh)。

风险与未覆盖边界说明

  • 残余边界:commitCheckpoint 内的锁交接与写入阶段共用了同一 runPath,本次测试直接覆盖 inspectCheckpointReplay 回放、Python inspect_checkpoint_replay 跨语言调用及 checkpoint_commit 相关 TS 全套,但未构造完整多进程锁迁移的 commitCheckpoint 端到端重放集成测试;补充写入路径中,未落盘的新建文件(ENOENT)仍要求与 resolve(runsDir) 同目录,不通过重定位分支放行,且 Python 侧 checkpoint_context_io.py 已统一用 .resolve() 对齐 runtime_root,不会破坏正常写入。
  • 远端 CI 诊断说明:按当前 wait_for_ci=false 审查策略不以远端 CI 作为充分或阻塞条件(仅作诊断附注:提交时 merge_state 为 BEHIND,mergeable=MERGEABLE,且基线到最新 origin/main 之间本 PR 涉及的 3 个文件无冲突改动)。

我的整体评价 / Verdict

本 PR 属于 goal_achieved:精准解决了 runtime_root 复制后 checkpoint_commit.ts 拒绝合法历史检查点产物的问题,语义与 #9161 的 readQuotaSpendEventFromRun 对齐,且同步强化了内部符号链接防护。

  • 长程与用户体验影响:long_horizon 为 preserved(迁移后的运行根目录不再在 refresh-state 检查点回放/修复阶段卡死,同时跨 Goal 与篡改路径仍严格阻断,不触发重复扣额或状态污染);user_experience 为 preserved,其中 visual_review 为 not_applicable(已核对全部 3 个变更文件仅涉及控制面 TS、单元测试与 tsconfig.control-plane.json,无渲染前端或 Lark UI 变更;无未核验渲染范围 unverified_scope=none)。
  • 语义对齐与架构评估:不引入新共享词汇、持久化 schema 或控制面开关(semantic_alignment 为 not_applicable,无共有词表扩张),架构评估为 retain(同步边界内聚于 checkpoint_commit.ts),兼容评估为 retain(同时保留原同目录直通分支与迁移路径的常规文件检查)。全部本地 TS/Python/premerge 验证均通过,无阻塞项(merge_state=BEHIND 与远端 CI 门禁由合并前流程单独检查)。

English verdict: APPROVE - exact head a3d8764 resolves relocated checkpoint artifacts inside the active goal runs directory while rejecting cross-goal, traversal, symlink, and non-file paths; local typecheck, 121 TS tests, Python boundary checks, and 14 premerge checks pass with no blocking findings.

@huangruiteng
huangruiteng merged commit 9f5ec7b into main Nov 21, 2026
42 of 48 checks passed
@huangruiteng
huangruiteng deleted the cursor/checkpoint-relocated-run-path-6200 branch November 21, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants